.TH cgi-exec 8 "February 2003" "" "cthulhu webserver"

.\"* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
.\"Copyright (C) 2002, 2003 Thomas M. Ogrisegg. All rights reserved
.\"* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

.SH NAME
cgi-exec \- Cthulhu execution daemon for CGI scripts
.SH SYNOPSIS
ipinit cgi-exec
.PP
.SH DESCRIPTION
.B cgi-exec
listens on an open socket for requests from cthulhu(8) which it satisfies
by executing the requested cgi scripts.

It should be run from
.B ipinit(8)
with an appropriate ipinit-script.

If cgi-exec is running as root it will run all scripts with the uid/gid of
the owner of the target script. This allows the safe execution of such
scripts. Keep in mind that all resource limits of cgi-exec are inherited to
it's child processes. This can be exploited to not allow cgi-scripts to
exhaust system resources.

Whenever cgi-exec receives a request from cthulhu(8) it will first try to
determine the working directory and the root-directory for the script it
should execute from <cthulhu-basedir>/conf/cgi-exec/<domain>. Thus, if
cgi-exec receives a request to execute /cgi-bin/foobar of the domain
example.org, then it will read the file <cthulhu-basedir>/conf/cgi-exec/example.org.

These configuration files are of the following format:

<program-wildcard>:<working-directory>:<root-directory>

If you don't want to set the workingdirectory or rootdirectory then just
leave it blank.

The environment for cgi-exec's child processes is read from
<cthulhu-basedir>/conf/cgi-exec/environ. It has the same format as
the /etc/environment file, which is
.B 'VARIABLE=VALUE'.

.SH EXAMPLES

The file <cthulhu-basedir>/conf/cgi-exec/example.org might look like:
.IP
.br
/cgi-bin/*:/var/tmp:
.br
/foo/bar.cgi::/usr/bar
.br
*.php3:/var/php/:
.br
/fnord/rotfl:/tmp:/usr
.PP

The first line is a wildcard for all scripts in /cgi-bin/ which says that
the current directory for these scripts is /var/tmp.

The second line means that /foo/bar.cgi should be executed with the root
directory /usr/bar.

The third line says that all PHP scripts should be executed with the working
directory set to /var/php.

The fourth line executes /fnord/rotfl with the root directory set to /usr
and the working directory to the subdirectory /tmp (thus the working is
/usr/tmp because of the different root directory).

The <cthulhu-basedir>/conf/cgi-exec/environ file might look like:

PATH=/bin:/usr/bin
SERVER_ADMIN=bofh@example.org

An example script for ipinit(8):
.IP
.br
server /var/cthulhu/bin/cgi-exec
.br
cwd /var/cthulhu
.br
bind 0:unix:/var/cthulhu/dev/cgi
.br
open 2>/var/cthulhu/log/cgi-errors.log
.br
openfiles 2048
.br
cputime 100
.br
fork
.RE
.PP
.SH REMARKS
Changing the uid/gid or the root directory of CGI scripts normally only works
if cgi-exec is beeing executed as root.

If scripts are executed with an alternative root directory (chroot) then
please make sure that the scripts reside _within_ that directory or it's sub-
directories, else cgi-exec will be unable to execute the script properly.

Some environment variables required by the CGI specifiecation are not auto-
matically set by cgi-exec. You have to manually add them to then 'environ'
file. These are as follows:

.br
SERVER_PORT
.br
GATEWAY_INTERFACE
.br
SERVER_PROTOCOL

It's recommended to set GATEWAY_INTERFACE to "CGI/1.1" and SERVER_PROTOCOL
to "HTTP/1.0", as cthulhu currently only supports HTTP/1.0 (and some HTTP/1.1
features).

SERVER_PORT is normally 80 - depending on your webserver configuration.

Further it's recommended to also add the following variables:

.br
SERVER_ADMIN
.br
PATH

SERVER_ADMIN is normally the person responsible for the webserver. E.g.
webmaster@example.org.

PATH is the system path in which other executables are beeing searched.
It is not beeing used by cgi-exec itself but might be used by the CGI
scripts it executes.

.SH NOTES

cgi-exec will reread it's configuration files after the receipt of a HUP
signal.

If you use UNIX sockets then you will have to remove the sockets after killing
cgi-exec, else ipinit will complain on it's next startup that the address is
still in use.

It's a security risk to grant applications other than cthulhu a connection to
the cgi exec daemon. Don't do it! (this means: DO NOT USE INTERNET SOCKETS!
Use UNIX domain sockets with appropriate permissions set instead).

.SH AUTHOR
cgi-exec was developed by Thomas M. Ogrisegg.

Please mail suggestions, bug-reports etc. to <tom-bugs@cthulhu.fnord.at>
.SH SEE ALSO
cthulhu(8), ipinit(8)
